feat: add pantheon doctor command for environment diagnostics#43
feat: add pantheon doctor command for environment diagnostics#43hazelian0619 wants to merge 1 commit intoaristoteleo:mainfrom
Conversation
JiwaniZakir
left a comment
There was a problem hiding this comment.
The _check_api_keys docstring explicitly says it "replicates" the four-step detection from check_and_run_setup(), but the duplication is a maintenance hazard — if the wizard's detection logic or the contents of PROVIDER_API_KEYS/CUSTOM_ENDPOINT_ENVS change, doctor.py will silently diverge and report a different result than the wizard would. The detection logic should be extracted into a shared utility (e.g., pantheon/utils/api_key_check.py) that both check_and_run_setup and _check_api_keys call, making synchronization structural rather than a comment-level promise.
Additionally, _check_r_runtime has a different return type (Optional[CheckResult]) compared to every other check function (CheckResult), forcing special-case handling in _collect_checks. A more uniform approach would be to have all check functions return CheckResult unconditionally and introduce a "SKIP" status (or a skipped: bool field) — this also makes it easier to add future optional checks without changing the collector's logic each time.
|
@hazelian0619 I think this is a great PR, but checking only these aspects isn’t sufficient at this point. Since Pantheon relies on an online frontend, network-related aspects also need to be checked. Additionally, folder accessibility needs to be verified, as Pantheon stores certain files in the root directory. Perhaps you could draw inspiration from OpenClaw’s “Doctor” approach to create a more comprehensive PR. |
feat: add
pantheon doctorcommand for environment diagnosticsSummary
Pantheon currently auto-checks for LLM provider API keys at startup
(
check_and_run_setup), but has no way to surface other commonenvironment misconfigurations before execution begins.
This PR adds an explicit
pantheon doctorcommand that makes theproject's existing environment contracts visible before a run starts,
following established CLI diagnostics patterns used by
flutter doctor,npm doctor,dbt debug, andbrew doctor.Motivation
Two concrete gaps this addresses:
1. Python version —
pyproject.tomldeclaresrequires-python = ">=3.10",but nothing checks this at runtime; mismatches only surface as cryptic
import failures.
2. Core package integrity —
ipykernel,jupyter-client, andnbformatare declared required dependencies. A broken or incomplete install
silently degrades notebook functionality with no clear diagnosis.
Additionally, the
roptional-dependency comment inpyproject.tomlexplicitly states "requires R installed on system". When a user installs
the
rextra but does not have R on PATH, the failure is currently silentuntil rpy2 is actually called.
Changes
pantheon/doctor.pyrun_doctor()runnerpantheon/__main__.pydoctorto auto-setup skip list, adddoctor()function, register infire.Fire()No other files are modified.
What
pantheon doctorcheckspyproject.toml requires-pythoncheck_and_run_setup()four-step detection:SKIP_SETUP_WIZARD→PROVIDER_API_KEYS→CUSTOM_ENDPOINT_ENVS→LLM_API_KEYipykernel/jupyter-client/nbformatimportableroptional extra — pyproject.toml comment: "requires R installed on system"All checks are output-only. The command never modifies the system.
Design notes
Why
doctorskipscheck_and_run_setup()The existing guard in
main()already skips the setup wizard whensys.argv[1] == "setup".doctoris added to this skip list for thesame reason: running
pantheon doctorshould surface the environmentstate, not trigger the interactive wizard. The one-character change
(
!= "setup"→not in ("setup", "doctor")) makes this explicit.Why
_check_api_keysmirrorscheck_and_run_setupexactlyRather than defining a new key-detection heuristic,
_check_api_keys()replicates the same four-step check from
check_and_run_setup()in thesame order (
SKIP_SETUP_WIZARD→PROVIDER_API_KEYS→CUSTOM_ENDPOINT_ENVS→ legacyLLM_API_KEY), so thatdoctorand thestartup wizard always agree on whether the environment is configured.
Non-goals
Backward compatibility
None — this is a pure addition. All existing commands are unchanged.
Testing
Manual test matrix:
CUSTOM_ANTHROPIC_API_KEYsetLLM_API_KEYset (legacy)SKIP_SETUP_WIZARD=1rpy2installed, R absentrpy2not installedpantheon doctor